servlet 3.1规范（servlet

ContentsContents ix1. Overview 11.1 What is a Servlet? 11.2 What is a Servlet Container? 11.3 An Example 21.4 Comparing Servlets with Other Technologies 31.5 Relationship to Java Platform, Enterprise Edition 31.6 Compatibility with Java Servlet Specification Version 2.5 41.6.1 Processing annotations 42. The Servlet Interface 52.1 Request Handling Methods 52.1.1 HTTP Specific Request Handling Methods 52.1.2 Additional Methods 62.1.3 Conditional GET Support 62.2 Number of Instances 62.2.1 Note About The Single Thread Model 72.3 Servlet Life Cycle 72.3.1 Loading and Instantiation 7x Java Servlet Specification • April 20132.3.2 Initialization 82.3.2.1 Error Conditions on Initialization 82.3.2.2 Tool Considerations 82.3.3 Request Handling 92.3.3.1 Multithreading Issues 92.3.3.2 Exceptions During Request Handling 92.3.3.3 Asynchronous processing 102.3.3.4 Thread Safety 202.3.3.5 Upgrade Processing 202.3.4 End of Service 213. The Request 233.1 HTTP Protocol Parameters 233.1.1 When Parameters Are Available 243.2 File upload 243.3 Attributes 253.4 Headers 253.5 Request Path Elements 263.6 Path Translation Methods 273.7 Non Blocking IO 283.8 Cookies 293.9 SSL Attributes 303.10 Internationalization 303.11 Request data encoding 313.12 Lifetime of the Request Object 314. Servlet Context 334.1 Introduction to the ServletContext Interface 334.2 Scope of a ServletContext Interface 33Contents xi4.3 Initialization Parameters 344.4 Configuration methods 344.4.1 Programmatically adding and configuring Servlets 354.4.1.1 addServlet(String servletName, String className) 354.4.1.2 addServlet(String servletName, Servlet servlet) 354.4.1.3 addServlet(String servletName, Class <? extendsServlet> servletClass) 354.4.1.4 <T extends Servlet> T createServlet(Class<T> clazz) 354.4.1.5 ServletRegistration getServletRegistration(StringservletName) 364.4.1.6 Map<String, ? extends ServletRegistration>getServletRegistrations() 364.4.2 Programmatically adding and configuring Filters 364.4.2.1 addFilter(String filterName, String className) 364.4.2.2 addFilter(String filterName, Filter filter) 364.4.2.3 addFilter(String filterName, Class <? extends Filter>filterClass) 374.4.2.4 <T extends Filter> T createFilter(Class<T> clazz) 374.4.2.5 FilterRegistration getFilterRegistration(StringfilterName) 374.4.2.6 Map<String, ? extends FilterRegistration>getServletRegistrations() 374.4.3 Programmatically adding and configuring Listeners 384.4.3.1 void addListener(String className) 384.4.3.2 <T extends EventListener> void addListener(T t) 384.4.3.3 void addListener(Class <? extends EventListener>listenerClass) 394.4.3.4 <T extends EventListener> voidcreateListener(Class<T> clazz) 394.4.3.5 Annotation processing requirements forprogrammatically added Servlets, Filters andListeners 40xii Java Servlet Specification • April 20134.5 Context Attributes 404.5.1 Context Attributes in a Distributed Container 414.6 Resources 414.7 Multiple Hosts and Servlet Contexts 424.8 Reloading Considerations 424.8.1 Temporary Working Directories 425. The Response 455.1 Buffering 455.2 Headers 465.3 Non Blocking IO 475.4 Convenience Methods 485.5 Internationalization 495.6 Closure of Response Object 505.7 Lifetime of the Response Object 506. Filtering 516.1 What is a filter? 516.1.1 Examples of Filtering Components 526.2 Main Concepts 526.2.1 Filter Lifecycle 526.2.2 Wrapping Requests and Responses 546.2.3 Filter Environment 546.2.4 Configuration of Filters in a Web Application 556.2.5 Filters and the RequestDispatcher 587. Sessions 617.1 Session Tracking Mechanisms 617.1.1 Cookies 617.1.2 SSL Sessions 62Contents xiii7.1.3 URL Rewriting 627.1.4 Session Integrity 627.2 Creating a Session 627.3 Session Scope 637.4 Binding Attributes into a Session 647.5 Session Timeouts 647.6 Last Accessed Times 657.7 Important Session Semantics 657.7.1 Threading Issues 657.7.2 Distributed Environments 657.7.3 Client Semantics 668. Annotations and pluggability 678.1 Annotations and pluggability 678.1.1 @WebServlet 678.1.2 @WebFilter 698.1.3 @WebInitParam 698.1.4 @WebListener 698.1.5 @MultipartConfig 708.1.6 Other annotations / conventions 708.2 Pluggability 718.2.1 Modularity of web.xml 718.2.2 Ordering of web.xml and web-fragment.xml 728.2.3 Assembling the descriptor from web.xml, web-fragment.xml andannotations 788.2.4 Shared libraries / runtimes pluggability 918.3 JSP container pluggability 938.4 Processing annotations and fragments 939. Dispatching Requests 95xiv Java Servlet Specification • April 20139.1 Obtaining a RequestDispatcher 959.1.1 Query Strings in Request Dispatcher Paths 969.2 Using a Request Dispatcher 969.3 The Include Method 979.3.1 Included Request Parameters 979.4 The Forward Method 989.4.1 Query String 989.4.2 Forwarded Request Parameters 989.5 Error Handling 999.6 Obtaining an AsyncContext 999.7 The Dispatch Method 1009.7.1 Query String 1009.7.2 Dispatched Request Parameters 10010. Web Applications 10310.1 Web Applications Within Web Servers 10310.2 Relationship to ServletContext 10310.3 Elements of a Web Application 10410.4 Deployment Hierarchies 10410.5 Directory Structure 10410.5.1 Example of Application Directory Structure 10610.6 Web Application Archive File 10610.7 Web Application Deployment Descriptor 10610.7.1 Dependencies On Extensions 10710.7.2 Web Application Class Loader 10710.8 Replacing a Web Application 10810.9 Error Handling 10810.9.1 Request Attributes 10810.9.2 Error Pages 109Contents xv10.9.3 Error Filters 11110.10 Welcome Files 11110.11 Web Application Environment 11210.12 Web Application Deployment 11310.13 Inclusion of a web.xml Deployment Descriptor 11311. Application Lifecycle Events 11511.1 Introduction 11511.2 Event Listeners 11511.2.1 Event Types and Listener Interfaces 11611.2.2 An Example of Listener Use 11711.3 Listener Class Configuration 11711.3.1 Provision of Listener Classes 11711.3.2 Deployment Declarations 11811.3.3 Listener Registration 11811.3.4 Notifications At Shutdown 11811.4 Deployment Descriptor Example 11811.5 Listener Instances and Threading 11911.6 Listener Exceptions 11911.7 Distributed Containers 12011.8 Session Events 12012. Mapping Requests to Servlets 12112.1 Use of URL Paths 12112.2 Specification of Mappings 12212.2.1 Implicit Mappings 12212.2.2 Example Mapping Set 12313. Security 12513.1 Introduction 125xvi Java Servlet Specification • April 201313.2 Declarative Security 12613.3 Programmatic Security 12613.4 Programmatic Security Policy Configuration 12813.4.1 @ServletSecurity Annotation 12813.4.1.1 Examples 13213.4.1.2 Mapping @ServletSecurity to security-constraint 13313.4.1.3 Mapping @HttpConstraint and@HttpMethodConstraint to XML. 13513.4.2 setServletSecurity of ServletRegistration.Dynamic 13613.5 Roles 13713.6 Authentication 13813.6.1 HTTP Basic Authentication 13813.6.2 HTTP Digest Authentication 13813.6.3 Form Based Authentication 13913.6.3.1 Login Form Notes 14013.6.4 HTTPS Client Authentication 14113.6.5 Additional Container Authentication Mechanisms 14113.7 Server Tracking of Authentication Information 14113.8 Specifying Security Constraints 14213.8.1 Combining Constraints 14313.8.2 Example 14413.8.3 Processing Requests 14613.8.4 Uncovered HTTP Protocol Methods 14713.8.4.1 Rules for Security Constraint Configuration 14913.8.4.2 Handling Uncovered HTTP Methods 14913.9 Default Policies 15013.10 Login and Logout 15114. Deployment Descriptor 153Contents xvii14.1 Deployment Descriptor Elements 15314.2 Rules for Processing the Deployment Descriptor 15414.3 Deployment Descriptor 15514.4 Deployment Descriptor Diagram 15514.5 Examples 17814.5.1 A Basic Example 17914.5.2 An Example of Security 18015. Requirements related to other Specifications 18315.1 Sessions 18315.2 Web Applications 18315.2.1 Web Application Class Loader 18315.2.2 Web Application Environment 18415.2.3 JNDI Name for Web Module Context Root URL 18415.3 Security 18515.3.1 Propagation of Security Identity in EJB™ Calls 18615.3.2 Container Authorization Requirements 18615.3.3 Container Authentication Requirements 18615.4 Deployment 18715.4.1 Deployment Descriptor Elements 18715.4.2 Packaging and Deployment of JAX-WS Components 18715.4.3 Rules for Processing the Deployment Descriptor 18915.5 Annotations and Resource Injection 18915.5.1 @DeclareRoles 19015.5.2 @EJB Annotation 19115.5.3 @EJBs Annotation 19215.5.4 @Resource Annotation 19215.5.5 @PersistenceContext Annotation 19315.5.6 @PersistenceContexts Annotation 193xviii Java Servlet Specification • April 201315.5.7 @PersistenceUnit Annotation 19415.5.8 @PersistenceUnits Annotation 19415.5.9 @PostConstruct Annotation 19415.5.10 @PreDestroy Annotation 19515.5.11 @Resources Annotation 19515.5.12 @RunAs Annotation 19615.5.13 @WebServiceRef Annotation 19715.5.14 @WebServiceRefs Annotation 19715.5.15 Contexts and Dependency Injection for Java EE requirements 197A. Change Log 199A.1 Changes since Servlet 3.0 199A.2 Changes since Servlet 3.0 Proposed Final Draft 201A.3 Changes since Servlet 3.0 Public Review 202A.4 Changes since Servlet 3.0 EDR 202A.5 Changes since Servlet 2.5 MR6 202A.6 Changes since Servlet 2.5 MR 5 203A.6.1 Clarify SRV 8.4 "The Forward Method" 203A.6.2 Update Deployment descriptor "http-method values allowed"203A.6.3 Clarify SRV 7.7.1 "Threading Issues" 204A.7 Changes Since Servlet 2.5 MR 2 204A.7.1 Updated Annotation Requirements for Java EE containers 204A.7.2 Updated Java Enterprise Edition Requirements 204A.7.3 Clarified HttpServletRequest.getRequestURL() 204A.7.4 Removal of IllegalStateException from HttpSession.getId() 205A.7.5 ServletContext.getContextPath() 205A.7.6 Requirement for web.xml in web applications 206A.8 Changes Since Servlet 2.4 206Contents xixA.8.1 Session Clarification 206A.8.2 Filter All Dispatches 207A.8.3 Multiple Occurrences of Servlet Mappings 207A.8.4 Multiple Occurrences Filter Mappings 208A.8.5 Support Alternative HTTP Methods with AuthorizationConstraints 209A.8.6 Minimum J2SE Requirement 210A.8.7 Annotations and Resource Injection 210A.8.8 SRV.9.9 ("Error Handling") Requirement Removed 210A.8.9 HttpServletRequest.isRequestedSessionIdValid() Clarification210A.8.10 SRV.5.5 ("Closure of Response Object") Clarification 210A.8.11 ServletRequest.setCharacterEncoding() Clarified 211A.8.12 Java Enterprise Edition Requirements 211A.8.13 Servlet 2.4 MR Change Log Updates Added 211A.8.14 Synchronized Access Session Object Clarified 211A.9 Changes Since Servlet 2.3 211